<html>
<head>
<title>User Manual: Dotdir</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<h1>5. The Dotdir</h1>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>

<p><i>
  None of the information in this section of the manual is needed to
  use and enjoy Olive.
</i></p>

<p>
  Olive keeps its configuration, raw data, and working data in a
  directory named '<code>~/.olive</code>'. This section describes the
  contents of that directory.
</p>


<h2 id="s10">5.1 The Config File</h2>
<p>
  The configuration file is named '<code>olive.yaml</code>'. As its
  extension indicates, it is
  a <a href="http://yaml.org/">YAML</a>-formatted file. If you are
  unfamiliar with YAML, you should read about it before manually
  editing this file.
</p>
<h3 id="s11">5.1.1 Miscellaneous Configuration</h3>
<p>
</p>
<dl>
  <dt>coe</dt>
  <dd>
    <b>Mnemonic:</b> Confirm On Exit<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether Olive termination is immediate (0)
    or confirmed (1). See <a href="options.html#s25">Section 3.2.5</a>.
  </dd>
  <dt>dst</dt>
  <dd>
    <b>Mnemonic:</b> Don't Show Titlebar<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether the first line of the Olive window
    is used as a titlebar (0) or to display live list data
    (1). See <a href="options.html#s24">Section 3.2.4</a>.
  </dd>
  <dt>gsp</dt>
  <dd>
    <b>Mnemonic:</b> Global Story Paging<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether keybindings are enabled so as to
    allow paging of the currently displayed story no matter where
    focus is. 1 is "bind", 0 is "don't
    bind". See <a href="options.html#s24">Section 3.2.4</a>.
  </dd>
  <dt>fos</dt>
  <dd>
    <b>Mnemonic:</b> Focus On Select<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether the Story Pane receives input
    focus (1) or not (0) when a story is selected in the List
    Pane. See <a href="options.html#s23">Section 3.2.3</a>.
  </dd>
  <dt>fr</dt>
  <dd>
    <b>Mnemonic:</b> First Run<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Marks whether Olive has been run before (1) or not
    (0). The only visible effect this has is the display of the
    first-run splash screen, so if you'd ever like to see that again
    now you know what to do.
  </dd>
  <dt>pw</dt>
  <dd>
    <b>Mnemonic:</b> Poll Wait<br/>
    <b>Type:</b> Positive Integer<br/>
    <b>Effect:</b> Sets the inital value, in minutes, of the delay
    between automatic poll feeds. See
    sections <a href="options.html#s30">3.3</a>
    and <a href="feeds.html#s40">4.4</a> for more info.
  </dd>
  <dt>sls</dt>
  <dd>
    <b>Mnemonic:</b> Show List Status<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether the status line will display story
    list stats (1) or not (0). See <a href="options.html#s21">Section
    3.2.1</a>.
  </dd>
  <dt>snu</dt>
  <dd>
    <b>Mnemonic:</b> Skip to Next Unread<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls the behavior of the prev/next commands:
    always select the story adjacent to the current selection (0) or
    seek to the next unread story
    (1). See <a href="options.html#s22">Section 3.2.2</a>.
  </dd>
  <dt>to</dt>
  <dd>
    <b>Mnemonic:</b> Time-Out<br/>
    <b>Type:</b> Positive Integer<br/>
    <b>Effect:</b> Sets the initial value for the network timeout of
    the internal LWP::UserAgent object which fetches
    feeds. See <a href="options.html#s40">Section 3.4</a>.
</dd>
  <dt>www</dt>
  <dd>
    <b>Mnemonic:</b> ...<br/>
    <b>Type:</b> String<br/>
    <b>Effect:</b> Contains the command string which is used to launch
    external browser sessions. See <a href="options.html#s50">Section
    3.5</a>.
  </dd>
</dl>
<h3 id="s12">5.1.2 Feeds</h3>
<p>
  All information about subscribed feeds is stored in a HOHOH named
  '<code>feeds</code>'. The full format is as follows:
</p>
<pre><code>  feeds:
    a_feed:
      disp: Display Title From User
      dormant: 0
      feed: http://feed/url
      force: 0
      last: 1119248150
      title: Actual Title From RSS Feed
      ttl: 86400
</code></pre>
<p>
  Where the '<code>a_feed</code>' stanza is repeated, with appropriate
  changes, for each subscribed feed. The meanings of the individual
  values is:
</p>
<ol>
  <li><b>disp:</b> The feed's user-chosen display name; displayed in
  the List Pane next to stories belonging to this feed.</li>
  <li><b>dormant:</b> Boolean marking the feed dormant or not.</li>
  <li><b>feed:</b> URL of the actual feed.</li>
  <li><b>force:</b> Boolean marking the feed as force-fetchable or not.</li>
  <li><b>last:</b>Value of <code>time()</code> as of the feed's last fetching.</li>
  <li><b>title:</b> Actual title of the feed, taken from the feed data.</li>
  <li><b>ttl:</b> The feed's time-to-live in seconds. Taken from the
  feed or given a value of 3600s in the absence of a value from the
  feed data.</li>
</ol>
<p>
  See <a href="feeds.html">Section 4</a> for more information.
</p>
<h3 id="s13">5.1.3 Customizing Keybindings</h3>
<p>
  There is no interface provided for changing keybindings within
  Olive. Not all functions can be rebound. The ones which can are
  altered via a HOH named '<code>keys</code>' in the config file. An
  example which creates custom bindings for the functions normally
  assigned to the '<code>[</code>' and '<code>]</code>' keys is:
</p>
<pre><code>  keys:
    next: n
    prev: p
</code></pre>
<p>
  Here is the list of bindable functions and their standard keys:
</p>
<table>
  <tr><th>Function</th><th>Key</th><th>Description</th></tr>
  <tr>
    <td>prev</td>
    <td><code>[</code></td>
    <td>Go to previous story</td>
  </tr>
  <tr>
    <td>next</td>
    <td><code>]</code></td>
    <td>Go to next story</td>
  </tr>
  <tr>
    <td>mark</td>
    <td><code>m</code></td>
    <td>Mark story read</td>
  </tr>
  <tr>
    <td>unmark</td>
    <td><code>u</code></td>
    <td>Mark story unread (unmark story)</td>
  </tr>
  <tr>
    <td>star</td>
    <td><code>s</code></td>
    <td>Toggle story starred/unstarred</td>
  </tr>
  <tr>
    <td>markall</td>
    <td><code>M</code></td>
    <td>Mark all stories read</td>
  </tr>
  <tr>
    <td>unmarkall</td>
    <td><code>U</code></td>
    <td>Mark all stories unread (unmark all)</td>
  </tr>
  <tr>
    <td>gpdn</td>
    <td>'<code> </code>' (Space)</td>
    <td>Global story paging: pagedown</td>
  </tr>
  <tr>
    <td>gpup</td>
    <td><code>-</code></td>
    <td>Global story paging: pageup</td>
  </tr>
  <tr>
    <td>focus</td>
    <td><code>w</code></td>
    <td>Shift focus between list/story panes</td>
  </tr>
  <tr>
    <td>link</td>
    <td><code>l</code></td>
    <td>Execute defined link command with story URL</td>
  </tr>
  <tr>
    <td>poll</td>
    <td><code>p</code></td>
    <td>Poll for updated feeds</td>
  </tr>
  <tr>
    <td>force</td>
    <td><code>P</code></td>
    <td>Force-poll feeds marked as forced</td>
  </tr>
  <tr>
    <td>filterf</td>
    <td><code>F</code></td>
    <td>Filter story list to show only stories from flagged feeds</td>
  </tr>
  <tr>
    <td>filters</td>
    <td><code>S</code></td>
    <td>Filter story list to show only starred stories</td>
  </tr>
</table>

<p>
  Olive does not check for duplicate bindings or stomping on a
  prebound key without providing a replacement. Also, be aware that
  you may need to quote your choice of key if it is a YAML special
  character (see the YAML spec for more information).
</p>


<h2 id="s20">5.2 The Error Log</h2>
<p>
  Olive logs all warnings and fatal error messages (trapped or
  otherwise) to a file named '<code>errors.log</code>'. On startup,
  this file is copied to '<code>errors.log.1</code>' before being
  overwritten, so there are logs for the past 2 runs available at any
  time.
</p>
<p>
  Error logs always start with a timestamp like this:
</p>
<pre><code>  -- Starting up at 2005-05-22T16:58:11 --
</code></pre>
<p>
  After that, there is no standard or predictable format for the
  contents of the file.
</p>
<p>
  Should Olive ever suddenly quit, or if you experience any problems
  or weird behavior, please look at the logfile(s) and file a bug (as
  per <a href="start.html#s50">Section 1.5</a>)
</p>

<h2 id="s30">5.3 The Story Database</h2>
<p>
  Olive does not operate upon the raw feeds it fetches over the
  network. It processes them after they are retrieved and stores
  the relevant data in a <a href="http://sqlite.org/">SQLite</a>
  database named '<code>story.db</code>'.
</p>
<p>
  The schema of the database is as follows:
</p>
<pre><code>  CREATE TABLE stories (id INTEGER PRIMARY KEY, 
                        nick TEXT, 
                        timestamp INT,
                        md5 TEXT, 
                        read INT, 
                        new INT, 
                        link TEXT, 
                        title TEXT, 
                        desc TEXT);
</code></pre>



<h2 id="s40">5.4 The Feeds Directory</h2>
<p>
  Downloaded feeds and the data needed to perform tests for HTTP 304
  status are stored in a subdirectory called
  '<code>feeds</code>'. Every feed you're subscribed to will have two
  files there, a file named as a possibly modified form of the feed
  nickname, and file with the same name as the first one, but with
  ".cache" appended.
</p>
<pre class='screen'>  mdxi@fornax:~$ ls .olive/feeds/
  atc             cnn_money        groklaw        mdxi         rjbs        
  atc.cache       cnn_money.cache  groklaw.cache  mdxi.cache   rjbs.cache  
  bbc_news        gloria           kate           olive        robert      
  bbc_news.cache  gloria.cache     kate.cache     olive.cache  robert.cache
</pre>
<p>
  The files with no extension hold the last downloaded copy of that
  feed. The <code>.cache</code> files hold HTTP header data needed to
  check if the feed has been updated when it is polled next.
</p>
<p>
  Files associated with a feed are unlinked when the feed is removed
  from your feed list.
</p>

<hr/>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>
<p>
$Id: dotdir.html 329 2005-11-23 22:39:12Z mdxi $
</p>
</body>
</html>
